home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kconfigdialogmanager.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  7.0 KB  |  237 lines
  1. /*
  2.  *  This file is part of the KDE libraries
  3.  *  Copyright (C) 2003 Benjamin C Meyer (ben+kdelibs at meyerhome dot net)
  4.  *  Copyright (C) 2003 Waldo Bastian <bastian@kde.org>
  5.  *
  6.  *  This library is free software; you can redistribute it and/or
  7.  *  modify it under the terms of the GNU Library General Public
  8.  *  License as published by the Free Software Foundation; either
  9.  *  version 2 of the License, or (at your option) any later version.
  10.  *
  11.  *  This library is distributed in the hope that it will be useful,
  12.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.  *  Library General Public License for more details.
  15.  *
  16.  *  You should have received a copy of the GNU Library General Public License
  17.  *  along with this library; see the file COPYING.LIB.  If not, write to
  18.  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19.  *  Boston, MA 02110-1301, USA.
  20.  */
  21. #ifndef KCONFIGDIALOGMANAGER_H
  22. #define KCONFIGDIALOGMANAGER_H
  23.  
  24. #include <qobject.h>
  25. #include <qptrlist.h>
  26. #include "kdelibs_export.h"
  27.  
  28. class KConfigSkeleton;
  29. class KConfigSkeletonItem;
  30. class QWidget;
  31. class QSqlPropertyMap;
  32.  
  33. /**
  34.  * @short Provides a means of automatically retrieving,
  35.  * saving and resetting KConfigSkeleton based settings in a dialog.
  36.  *
  37.  * The KConfigDialogManager class provides a means of automatically
  38.  * retrieving, saving and resetting basic settings.
  39.  * It also can emit signals when settings have been changed
  40.  * (settings were saved) or modified (the user changes a checkbox
  41.  * from on to off).
  42.  *
  43.  * The names of the widgets to be managed have to correspond to the names of the
  44.  * configuration entries in the KConfigSkeleton object plus an additional
  45.  * "kcfg_" prefix. For example a widget named "kcfg_MyOption" would be
  46.  * associated to the configuration entry "MyOption".
  47.  *
  48.  * KConfigDialogManager uses the QSqlPropertyMap class to determine if it can do
  49.  * anything to a widget.  Note that KConfigDialogManager doesn't  require a
  50.  * database, it simply uses the functionality that is built into the
  51.  * QSqlPropertyMap class.  New widgets can be added to the map using
  52.  * QSqlPropertyMap::installDefaultMap().  Note that you can't just add any
  53.  * class.  The class must have a matching Q_PROPERTY(...) macro defined.
  54.  *
  55.  * For example (note that KColorButton is already added and it doesn't need to
  56.  * manually added):
  57.  *
  58.  * kcolorbutton.h defines the following property:
  59.  * \code
  60.  * Q_PROPERTY( QColor color READ color WRITE setColor )
  61.  * \endcode
  62.  *
  63.  * To add KColorButton the following code would be inserted in the main.
  64.  *
  65.  * \code
  66.  * kapp->installKDEPropertyMap();
  67.  * QSqlPropertyMap *map = QSqlPropertyMap::defaultMap();
  68.  * map->insert("KColorButton", "color");
  69.  * \endcode
  70.  *
  71.  * If you add a new widget to the QSqlPropertyMap and wish to be notified when
  72.  * it is modified you should add its signal using addWidgetChangedSignal().
  73.  
  74.  * @since 3.2
  75.  * @author Benjamin C Meyer <ben+kdelibs at meyerhome dot net>
  76.  * @author Waldo Bastian <bastian@kde.org>
  77.  */
  78. class KDECORE_EXPORT KConfigDialogManager : public QObject {
  79.  
  80. Q_OBJECT
  81.  
  82. signals:
  83.   /**
  84.    * One or more of the settings have been saved (such as when the user
  85.    * clicks on the Apply button).  This is only emitted by updateSettings()
  86.    * whenever one or more setting were changed and consequently saved.
  87.    */
  88.   void settingsChanged();
  89.  
  90.   /**
  91.    * TODO: Verify
  92.    * One or more of the settings have been changed.
  93.    * @param widget - The widget group (pass in via addWidget()) that
  94.    * contains the one or more modified setting.
  95.    * @see settingsChanged()
  96.    */
  97.   void settingsChanged( QWidget *widget );
  98.  
  99.   /**
  100.    * If retrieveSettings() was told to track changes then if
  101.    * any known setting was changed this signal will be emitted.  Note
  102.    * that a settings can be modified several times and might go back to the
  103.    * original saved state. hasChanged() will tell you if anything has
  104.    * actually changed from the saved values.
  105.    */
  106.   void widgetModified();
  107.  
  108.  
  109. public:
  110.  
  111.   /**
  112.    * Constructor.
  113.    * @param parent  Dialog widget to manage
  114.    * @param conf Object that contains settings
  115.    * @param name - Object name.
  116.    */
  117.    KConfigDialogManager(QWidget *parent, KConfigSkeleton *conf, const char *name=0);
  118.  
  119.   /**
  120.    * Destructor.
  121.    */
  122.   ~KConfigDialogManager();
  123.  
  124.   /**
  125.    * Add additional widgets to manage
  126.    * @param widget Additional widget to manage, inlcuding all its children
  127.    */
  128.   void addWidget(QWidget *widget);
  129.  
  130.   /**
  131.    * Returns whether the current state of the known widgets are
  132.    * different from the state in the config object.
  133.    */
  134.   bool hasChanged();
  135.  
  136.   /**
  137.    * Returns whether the current state of the known widgets are
  138.    * the same as the default state in the config object.
  139.    */
  140.   bool isDefault();
  141.  
  142. public slots:
  143.   /**
  144.    * Traverse the specified widgets, saving the settings of all known
  145.    * widgets in the settings object.
  146.    *
  147.    * Example use: User clicks Ok or Apply button in a configure dialog.
  148.    */
  149.   void updateSettings();
  150.  
  151.   /**
  152.    * Traverse the specified widgets, sets the state of all known
  153.    * widgets according to the state in the settings object.
  154.    *
  155.    * Example use: Initialisation of dialog.
  156.    * Example use: User clicks Reset button in a configure dialog.
  157.    */
  158.   void updateWidgets();
  159.  
  160.   /**
  161.    * Traverse the specified widgets, sets the state of all known
  162.    * widgets according to the default state in the settings object.
  163.    *
  164.    * Example use: User clicks Defaults button in a configure dialog.
  165.    */
  166.   void updateWidgetsDefault();
  167.  
  168. protected:
  169.  
  170.   /**
  171.    * @param trackChanges - If any changes by the widgets should be tracked
  172.    * set true.  This causes the emitting the modified() signal when
  173.    * something changes.
  174.    * TODO: @return bool - True if any setting was changed from the default.
  175.    */
  176.   void init(bool trackChanges);
  177.  
  178.   /**
  179.    * Recursive function that finds all known children.
  180.    * Goes through the children of widget and if any are known and not being
  181.    * ignored, stores them in currentGroup.  Also checks if the widget
  182.    * should be disabled because it is set immutable.
  183.    * @param widget - Parent of the children to look at.
  184.    * @param trackChanges - If true then tracks any changes to the children of
  185.    * widget that are known.
  186.    * @return bool - If a widget was set to something other then its default.
  187.    */
  188.   bool parseChildren(const QWidget *widget, bool trackChanges);
  189.  
  190.   /**
  191.    * Set a property
  192.    */
  193.   void setProperty(QWidget *w, const QVariant &v);
  194.  
  195.   /**
  196.    * Retrieve a property
  197.    */
  198.   QVariant property(QWidget *w);
  199.  
  200.   /**
  201.    * Setup secondary widget properties
  202.    */
  203.   void setupWidget(QWidget *widget, KConfigSkeletonItem *item);
  204.  
  205. protected:
  206.   /**
  207.    * KConfigSkeleton object used to store settings
  208.    */
  209.   KConfigSkeleton *m_conf;
  210.  
  211.   /**
  212.    * Dialog being managed
  213.    */
  214.   QWidget *m_dialog;
  215.  
  216.   /**
  217.    * Pointer to the property map for easy access.
  218.    */
  219.   QSqlPropertyMap *propertyMap;
  220.  
  221.   /**
  222.    * Map of the classes and the signals that they emit when changed.
  223.    */
  224.   QMap<QString, QCString> changedMap;
  225.  
  226. private:
  227.   class Private;
  228.   /**
  229.    * KConfigDialogManager Private class.
  230.    */
  231.   Private *d;
  232.  
  233. };
  234.  
  235. #endif // KCONFIGDIALOGMANAGER_H
  236.  
  237.